socket.io-client

What is socket.io-client?

The socket.io-client npm package is a client-side library that enables real-time, bidirectional and event-based communication between web clients and servers. It works on every platform, browser or device, focusing equally on reliability and speed.

What are socket.io-client's main functionalities?

Connecting to a server

This code sample demonstrates how to connect to a Socket.IO server running on localhost at port 3000.

const io = require('socket.io-client');
const socket = io('http://localhost:3000');

Emitting events

This code sample shows how to emit an event to the server with an event name and associated data.

socket.emit('event_name', { some: 'data' });

Listening for events

This code sample illustrates how to listen for events emitted by the server and handle them with a callback function.

socket.on('event_name', function(data) {
  console.log(data);
});

Disconnecting from the server

This code sample shows how to handle a disconnection event when the client gets disconnected from the server.

socket.on('disconnect', function() {
  console.log('Disconnected from server');
});

Other packages similar to socket.io-client

ws

The 'ws' package is a simple to use, blazing fast, and thoroughly tested WebSocket client and server implementation. Unlike socket.io-client, which provides an abstraction over WebSocket with additional features like auto-reconnection, 'ws' is a bare WebSocket implementation.

faye-websocket

Faye is a set of tools for simple publish-subscribe messaging between web clients. It's similar to socket.io-client in that it provides an abstraction over WebSocket for real-time communication, but it has a different API and feature set.

sockjs-client

SockJS-client is a browser JavaScript library that provides a WebSocket-like object. SockJS gives you a coherent, cross-browser, Javascript API which creates a low latency, full duplex, cross-domain communication channel between the browser and the web server, with WebSockets or without. It is similar to socket.io-client but focuses more on providing fallback options for environments where WebSocket is not available.

README

socket.io-client

How to use

A standalone build of socket.io-client is exposed automatically by the socket.io server as /socket.io/socket.io.js. Alternatively you can serve the file socket.io.js or socket.io.min.js found in the dist folder.

<script src="/socket.io/socket.io.js"></script>
<script>
  var socket = io('http://localhost');
  socket.on('connect', function(){});
  socket.on('event', function(data){});
  socket.on('disconnect', function(){});
</script>

Socket.IO is compatible with browserify.

Node.JS (server-side usage)

Add socket.io-client to your package.json and then:

var socket = require('socket.io-client')('http://localhost');
socket.on('connect', function(){});
socket.on('event', function(data){});
socket.on('disconnect', function(){});

API

IO(url:String, opts:Object):Socket

Exposed as the io namespace in the standalone build, or the result of calling require('socket.io-client').

When called, it creates a new Manager for the given URL, and attempts to reuse an existing Manager for subsequent calls, unless the multiplex option is passed with false.

The rest of the options are passed to the Manager constructor (see below for details).

A Socket instance is returned for the namespace specified by the pathname in the URL, defaulting to /. For example, if the url is http://localhost/users, a transport connection will be established to http://localhost and a Socket.IO connection will be established to /users.

IO#protocol

Socket.io protocol revision number this client works with.

IO#Socket

Reference to the Socket constructor.

IO#Manager

Reference to the Manager constructor.

IO#Emitter

Reference to the Emitter constructor.

Manager(url:String, opts:Object)

A Manager represents a connection to a given Socket.IO server. One or more Socket instances are associated with the manager. The manager can be accessed through the io property of each Socket instance.

The opts are also passed to engine.io upon initialization of the underlying Socket.

Options:

• reconnection whether to reconnect automatically (true)
• reconnectionAttempts (Infinity) before giving up
• reconnectionDelay how long to initially wait before attempting a new reconnection (1000). Affected by +/- randomizationFactor, for example the default initial delay will be between 500 to 1500ms.
• reconnectionDelayMax maximum amount of time to wait between reconnections (5000). Each attempt increases the reconnection delay by 2x along with a randomization as above
• randomizationFactor (0.5), 0 <= randomizationFactor <= 1
• timeout connection timeout before a connect_error and connect_timeout events are emitted (20000)
• autoConnect by setting this false, you have to call manager.open whenever you decide it's appropriate

Events

• connect_error. Fired upon a connection error. Parameters:
  • Object error object
• connect_timeout. Fired upon a connection timeout.
• reconnect. Fired upon a successful reconnection. Parameters:
  • Number reconnection attempt number
• reconnect_attempt. Fired upon an attempt to reconnect.
• reconnecting. Fired upon an attempt to reconnect. Parameters:
  • Number reconnection attempt number
• reconnect_error. Fired upon a reconnection attempt error. Parameters:
  • Object error object
• reconnect_failed. Fired when couldn't reconnect within reconnectionAttempts
• ping. Fired when a ping packet is written out to the server.
• pong. Fired when a pong is received from the server. Parameters:
  • Number number of ms elapsed since ping packet (i.e.: latency).

The events above are also emitted on the individual sockets that reconnect that depend on this Manager.

Manager#reconnection(v:Boolean):Manager

Sets the reconnection option, or returns it if no parameters are passed.

Manager#reconnectionAttempts(v:Boolean):Manager

Sets the reconnectionAttempts option, or returns it if no parameters are passed.

Manager#reconnectionDelay(v:Boolean):Manager

Sets the reconectionDelay option, or returns it if no parameters are passed.

Manager#reconnectionDelayMax(v:Boolean):Manager

Sets the reconectionDelayMax option, or returns it if no parameters are passed.

Manager#timeout(v:Boolean):Manager

Sets the timeout option, or returns it if no parameters are passed.

Socket

Socket#id:String

A property on the socket instance that is equal to the underlying engine.io socket id.

The property is present once the socket has connected, is removed when the socket disconnects and is updated if the socket reconnects.

Socket#compress(v:Boolean):Socket

Sets a modifier for a subsequent event emission that the event data will only be compressed if the value is true. Defaults to true when you don't call the method.

socket.compress(false).emit('an event', { some: 'data' });

Events

• connect. Fired upon a connection including a successful reconnection.
• error. Fired upon a connection error Parameters:
  • Object error data
• disconnect. Fired upon a disconnection.
• reconnect. Fired upon a successful reconnection. Parameters:
  • Number reconnection attempt number
• reconnect_attempt. Fired upon an attempt to reconnect.
• reconnecting. Fired upon an attempt to reconnect. Parameters:
  • Number reconnection attempt number
• reconnect_error. Fired upon a reconnection attempt error. Parameters:
  • Object error object
• reconnect_failed. Fired when couldn't reconnect within reconnectionAttempts

License

MIT